How to use FlashAir IoT Hub API

Latest update: September 2017

Overview

In this tutorial I will introduce the FlashAir IoT Hub API and explain the procedure for using it.

FlashAir IoT Hub provides an API that can be used to develop programs accessing FlashAir such as Web services and applications.
By using FlashAir IoT Hub API, let's all develop web services and applications that make use of FlashAir.
In this tutorial we will explain the preparation for using the API, but since the next time we will introduce the application programming using the API with concrete examples, so please refer to it when developing the application.

About API

FlashAir IoT Hub API is RESTful and easy to understand design. The API specification is published in FlashAir IoT Hub API document . API Please use FlashAir IoT Hub Terms of Use acceptance.

About authentication

The FlashAir IoT Hub API has the following authentication methods.

  • Device authentication
    Basic authentication using the access token acquired in FlashAir registration.
    It is mainly used to register data from FlashAir to FlashAir IoT Hub, such as the value of GPIO of FlashAir.
  • Client authentication
    It authenticates whether it is an application registered by the developer. The access token issued after authentication is required for user token authentication to be described later.
    For application authentication, we use information (developer ID, etc.) when the developer registered the application beforehand, so developers need to embed those information in the application.
  • User token authentication
    It is authentication according to OAuth 2.0. It is mainly used in applications that refer to FlashAir data registered in FlashAir IoT Hub API.
    Along with the above-mentioned client authentication, the user needs to authorize access when using the application.
    In this tutorial, the access token issued when this access is authorized is referred to as a user token.

In addition, the authentication method used for each API is decided. For example, using user token authentication for an API for which device authentication is specified will result in an error. However, some APIs can use multiple authentication methods.

Please see the FlashAir IoT Hub API document for how to authenticate each API.

In this tutorial, I will not touch the detailed specification of OAuth 2.0. Please refer to the following.

Flow of use

Let's use the FlashAir IoT Hub API. Follow the procedure below.

API usage procedure overview
Application user Application developers
1. Account registration Account registration
2. - Application registration
3. Access authorization Access authorization
4. - Token issuance

I will explain the procedure of each of the application user and the application developer.

Procedure of application user

This is the procedure of using the application using FlashAir IoT Hub API.

Account registration

Please register your FlashAir IoT Hub account according to Register / Login.

Access authorization

The application displays the login screen of FlashAir IoT Hub. Please login with yourself (application user) account.

Authorization login screen

We will confirm that the application can access the data of FlashAir IoT Hub, so if you agree, please click the approval button.

Authorization screen

With this, applications using FlashAir IoT Hub will be available.

Procedure of the application developer

This is the procedure for using the FlashAir IoT Hub API in the application.

Account registration

Please register your FlashAir IoT Hub account according to Register / Login.

Application registration

Access authorization according to OAuth 2.0 (RFC 6749) and OAuth PKCE (RFC 7636) is necessary for use of FlashAir IoT Hub API.
Since access is authorized based on the information of the application, please input necessary information and register the application.

Please login to FlashAir IoT Hub and click the Developer's Site link on the screen.

Link to developer site

Please click the Add app link on the developer site screen.

Application addition link

Enter necessary information and click the add button, the application will be registered.

Application information registration
Item Necessity Description
Name Required Name of the application.
Description Optional Overview of the application.
URL Optional URL of the application provision site or web service.
Type Required

Approval method according to usage form of client.

  • Server-side Web application (Authorization Code)
    It is an authorization method assuming use from a Web service executed on the Web server.
    Authorize access from the client according to OAuth 2.0 Authorization Code Grant of RFC 6749.
  • Client-side (JavaScript) Web application (Implicit)
    It is an authorization method assuming use from JavaScript loaded on the client.
    Authorize access from the client according to OAuth 2.0 Implicit Grant of RFC 6749.
  • Mobile/desktop application (OAuth PKCE)
    It is an approval method assuming use from a native application for smartphone or a desktop application.
    Authorize access from the client according to OAuth PKCE of RFC 7636.
Scope Required

Access authority of FlashAir IoT Hub API.

  • Reference only
    Only API concerning data acquisition is available.
  • Reference and Change
    API for data reference and change is available.
Redirect URL Required The URL to redirect after authorizing access on the authorization screen.
When redirecting, specify the authorization code to the parameters of the URL, so please specify the URL accessible by the web service or application.

After registration, the ID of the application will be displayed. The ID is used for requesting authorization. Let's implement it so that it can refer to this ID by Web service or application.

Application list

Access authorization

We will authorize you to access FlashAir IoT Hub.

Let's implement the application to display approval screen of FlashAir IoT Hub and obtain approval from application user.
Access authorization is done by accessing the FlashAir IoT Hub API. At that time, some parameters and procedures differ depending on the type of application you registered.

First, let's explain the basic access authorization procedure, so let's grasp the overall flow.
Next, I will explain details by type, so please see it according to the application you want to develop.

Access authorization flow

Access authorization is done in the following procedure.

  1. Authorization request
    Please inform the application user that access to FlashAir IoT Hub is necessary and access the authorization request API. When accessing the authorization request API, the login screen of FlashAir IoT Hub is displayed.
    In order to access the authorization request API, client authentication is required.
  2. Acquiring access authorization and authorization code
    When the application user logs in and approves the access, it passes the value of the authorization code to the application.
    This authorization code serves as a voucher for token issuance.

Did you grasp the flow of access authorization? Next, I will explain the procedure by type of application.

For server side web application

Authorization request

Let's access the URL of authorization request for server side web application with the following parameters from the application from the browser.

Parameters Necessity Description
response_type Required Response type. code fixed.
client_id Required Client ID. Please specify the ID of the application displayed on the developer's site screen or application details screen.
redirect_uri Optional Client's redirect URL. Please specify the URL of the page to be displayed after authorization on the authorization request screen. If omitted, the value specified in the redirect URL is used when registering the application.
state Required

A random number character string for CSRF countermeasure specified by the client. Give the same value to the parameter state of the redirect URL.
As a measure against CSRF, the client should verify that the value of this state and the value of state given to the redirect URL are the same.

Reference:

scope Optional

Scope string for access authorization. Please specify one of the following values. More than one can be specified with a space delimiter. If omitted, the value specified by the scope at application registration will be used.

  • flashair.write
    A value that represents the authority to change data
  • flashair.read
    A value representing authority of data reference
  • user.read
    A value that represents the authority of user information reference

Acquiring access authorization and authorization code

When you access authorization request for server side web application , the login screen of FlashAir IoT Hub is displayed.
When the application user logs in and approves the access on the authorization request screen, it redirects by assigning the following parameter to redirect_uri, so please obtain it with the application that developed the parameter .

  • code
    Authorization code. It is used for token issuance.
  • state
    A random number character string for CSRF countermeasure specified by the client. Please verify that it is the same value as state specified at the time of request.

For example, if redirect_uri is https://example.com/callback, it will be redirected to the following URL.

https://example.com/callback?code=xxxxxxxxxxxxxxxxxxxxxx&state=xyz

For mobile / desktop application

Authorization request

Please access the URL of authorization request for mobile desktop application with the following parameters from the application.

Parameters Necessity Description
response_type Required Response type. code fixed.
client_id Required Client ID. Please specify the ID of the application displayed on the developer's site screen or application details screen.
redirect_uri Optional Client's redirect URL. Please specify the URL of the page to be displayed after authorization on the authorization request screen. If omitted, the value specified in the redirect URL is used when registering the application.
state Required

A random number character string for CSRF countermeasure specified by the client. Give the same value to the parameter state of the redirect URL.
As a measure against CSRF, the client should verify that the value of this state and the value of state given to the redirect URL are the same.

Reference:

scope Optional

Scope string for access authorization. Please specify one of the following values. More than one can be specified with a space delimiter. If omitted, the value specified by the scope at application registration will be used.

  • flashair.write
    A value that represents the authority to change data
  • flashair.read
    A value representing authority of data reference
  • user.read
    A value that represents the authority of user information reference
code_challenge_method Required How to generate a challenge code. Corresponds only to S256.
code_challenge Required

Challenge code. Based on the OAuth PKCE of RFC 7636, generate it from the value of code_verifier.
code_verifier is used for token issuance.
For challenge code generation method only S256 is supported, and it is necessary to satisfy the following expression. (Quoted from RFC 7636)

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

Reference:

Acquiring access authorization and authorization code

The operation after accessing authorization Request for Mobile Desktop Application and the method of getting the authorization code are the same as authorization Request for Server Side Web Application .

For client side web application

Authorization request

Please access the URL of authorization request for client side web application with the following parameters from the application.

Parameters Necessity Description
response_type Required Response type. token fixed.
client_id Required Client ID. Please specify the ID of the application displayed on the developer's site screen or application details screen.
redirect_uri Optional Client's redirect URL. Please specify the URL of the page to be displayed after authorization on the authorization request screen. If omitted, the value specified in the redirect URL is used when registering the application.
state Required

A random number character string for CSRF countermeasure specified by the client. Give the same value to the parameter state of the redirect URL.
As a measure against CSRF, the client should verify that the value of this state and the value of state given to the redirect URL are the same.

Reference:

scope Optional

Scope string for access authorization. Please specify one of the following values. More than one can be specified with a space delimiter.

  • flashair.write
    A value that represents the authority to change data
  • flashair.read
    A value representing authority of data reference
  • user.read
    A value that represents the authority of user information reference

Accept access authorization and user token

After accessing authorization request for client side web application , it is the same as requesting for the server-side web application authorization to display the login screen, but please be aware that the user token will be returned directly after the access approval.

When you click the approval button, redirect it by adding the following parameter to redirect_uri. Please obtain the parameter with the application that developed it.

  • access_token
    User token. When requesting the FlashAir IoT Hub API that performs user token authentication, add the following to the HTTP header. 
    Authorization: Bearer <access_token>
  • token_type
    Token type. FlashAir IoT Hub API supports only Bearer.
  • expires_in
    User token expiration date (unit: second). After expiration of the expiration date, the user token will be invalid.
    In that case please obtain a new user token.
  • state
    A random number character string for CSRF countermeasure specified by the client. Please verify that it is the same value as state specified at the time of request.
  • scope
    Scope string for access authorization. We will return the value specified at the time of the request.

For example, if redirect_uri is https://example.com/callback, it will be redirected to the following URL.
Please note that the parameter is # rather than ?.

https://example.com/callback#access_token=xxxxxxxxxxxxxxxxxxxx&state=xyz&token_type=bearer&expires_in=86400&scope=user%2eread%20flashair%2eread%20flashair%2ewrite

Token issuance

If you get the authorization code by access authorization, let's issue the user token with token issue of FlashAir IoT Hub API.
In order to access to the API of token issue will require a client authentication .

In the case of client side web application, this task is unnecessary because it issues user token by access authorization.

Token issue has new issue and update done after expiration date.
By updating, you can acquire a new user token without making the application user authorize access to the application each time, so it will be necessary for the convenience of the user.

The user token issuance is different in case of new issue and update, and some parameters are different depending on the type of application.

How to issue a token


Also, regardless of how token is issued token acquisition method is all the same.

Issuing token of server side web application (new issue)
Parameters Necessity Description
grant_type Required

Grant type. authorization_code fixed.
code Required Authorization code. Please specify the authorization code obtained by access authorization.
client_id Required Client ID. Please specify the ID value displayed on the application list screen or details screen.
redirect_uri ※ Client's redirect URL. ※ Required if redirect_uri is specified in access authorization.
Otherwise you can omit it. If omitted, the value specified in the redirect URL is used when registering the application.
Issuing tokens for mobile / desktop applications (new issue)
Parameters Necessity Description
grant_type Required

Grant type. authorization_code fixed.
code Required Authorization code. Please specify the authorization code obtained by access authorization.
client_id Required Client ID. Please specify the ID value displayed on the application details screen.
redirect_uri ※ Client's redirect URL. ※ Required if redirect_uri is specified in access authorization.
Otherwise you can omit it. If omitted, the value specified in the redirect URL is used when registering the application.
code_verifier Required Verification code. Value used for challenge code generation.
Issuing a token (update)
Parameters Necessity Description
grant_type Required

Grant type. refresh_token fixed.
refresh_token Required Update token. Specify the value of refresh_token obtained at the time of previous user token acquisition.
scope Optional

Scope string for access authorization. Please specify one of the following values. More than one can be specified with a space delimiter. If omitted, the value specified by the scope at application registration will be used.

  • flashair.write
    A value that represents the authority to change data
  • flashair.read
    A value representing authority of data reference
  • user.read
    A value that represents the authority of user information reference

How to get a token

When issuing a token with FlashAir IoT Hub API, the value of JSON format is returned. The sample values are shown below. 

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}
  • access_token
    User token. When requesting the FlashAir IoT Hub API that performs user token authentication, add the following to the HTTP header. 
    Authorization: Bearer <access_token>
  • token_type
    Token type. FlashAir IoT Hub API supports only Bearer.
  • expires_in
    User token expiration date (unit: second). After expiration of the expiration date, the user token will be invalid.
    In that case please update the token and get a new user token.
  • refresh_token
    Update token. It is used when updating the user token with the same authorization method.

Issuance development token

Normally, the user token must be issued according to OAuth 2.0 in the above procedure, but if the developer wants to use it immediately without issuing a user token to a third party, such as when developing applications, from the screen of FlashAir IoT Hub you can issue user token without authorization.

To publish the development token, after registering the application, open the application details screen from the list and click the Get link of the access token.

Before acquisition of user token

Since the user token is displayed on the screen, please use that value. Please note that there is an expiration date.

After obtaining user token

The following tutorial introduces samples that actually use the FlashAir IoT Hub API.